home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Workbench / Misc / GURU30EN.LHA / Guru3.0 - English / TheGuru / Docs / Guru.doc < prev    next >
Encoding:
Text File  |  1994-11-13  |  16.3 KB  |  457 lines
  1. This is the documentation of:
  2.  
  3. Program  : The Guru 3.00 (November 8, 1994)
  4. Language : Assembly
  5. Author   : Emiel Lensink
  6.  
  7.  
  8. DISCLAIMER:
  9.  
  10.  Although I (the author) have thoroughly tested 'The Guru' and have done
  11.  everything possible to make the progra reliable, you use it AT YOUR OWN
  12.  RISK! This software comes 'as is'; no warranties whatsoever. I am not
  13.  responsible for any damage caused by using this program, either direct
  14.  or indirect. If this program spontaneously low level formats your computer,
  15.  crashes your harddisk, blows your nose, or melts your neighbours, I AM
  16.  NOT RESPONSIBLE !!!
  17.  
  18.  
  19. DISTRIBUTION:
  20.  
  21.  'The Guru' is freely redistributable. You may give it to your friends, your
  22.  neighbours, to anybody you know and don't know. Spread the word AND the
  23.  disk! 'The Guru' may be includesd in PD libraries, on coverdisks, on CD's
  24.  etc. You may archive the files as long as they are unaltered after
  25.  dearchieving. The only restriction I make is that the program MAY NOT BE
  26.  SOLD FOR PROFIT, and that you keep all the files together. You should have
  27.  the following files:
  28.  
  29.     TheGuru(.info)                (drawer)
  30.       Guru3.0(.info)
  31.       Error.data(.info)
  32.       Docs(.info)                 (drawer)
  33.         Guru.guide(.info)
  34.         Guru.doc(.info)
  35.         Guru.iff(.info)
  36.  
  37.     General(.info)                (drawer)
  38.       SimErr(.info)
  39.       Faults(.info)
  40.       CrashZero(.info)
  41.  
  42.     MAGICons(.info)               (drawer)
  43.       Guru3.0.info
  44.                 
  45.     Sources(.info)                (drawer)
  46.       Guru30.s(.info)
  47.       Fault.s(.info)
  48.       CrashZero.s(.info)
  49.       SimErr.s(.info)
  50.       Gadgets.i(.info)
  51.       GuruLogo.i(.info)
  52.  
  53.  If your set is not complete I advise you not to use the program(s), because
  54.  of the possibility of viruses etc.
  55.  
  56.  
  57. POSTWARE:
  58.  
  59.  This program is postware. This means that if you like it and use the
  60.  program you should send me a postcard of your hometown or country.
  61.   
  62.  My address is:
  63.  Emiel Lensink
  64.  Notengaarde 33
  65.  3992JR Houten
  66.  Holland
  67.  
  68.  
  69. GENERAL GURU KNOWLEDGE:
  70.  
  71.  Every amiga owner has seen a guru message or software error as they are
  72.  called in kickstart 2.0 and above at least once in his/her life. That 
  73.  nasty red flashing box has a purpose; the two numbers in the box can tell
  74.  you why your amiga crashed. The numbers take the following form:
  75.  
  76.  +----------------------------------------------------------------------+
  77.  |     Software failure.        Press left mouse button to continue.    |
  78.  |                                                                      |
  79.  |                 Error: 12345678   Task: 87654321                     |
  80.  +----------------------------------------------------------------------+
  81.  
  82.  You see two numbers here, one behind error and one behind task.
  83.  The one behind task is the address in memory where the crash occurred.
  84.  You can use a monitor and/or dissassembler on that address to see the
  85.  instruction(s) that caused the error. The number behind error is the
  86.  real important one, it tells you precisely what error occurred.
  87.  
  88.  There are three basic types of guru-messages, both in recovery and
  89.  deadend types. 
  90.  
  91. 1- PROCESSOR EXCEPTIONS:
  92.  This is your 680x0 speaking to you. This occurs if the processor p.e.
  93.  doesn't understand an instruction.
  94.  
  95. 2- SPECIFIC ALERTS:
  96.  These are error codes generated by a specific subsystem of the OS.,
  97.  for example dos.library or graphics.library. This is the most frequent
  98.  occuring kind of error. Some programs generate their own GURU alerts,
  99.  but those are of course not included in the guru (cos I don't have 'em).
  100.  
  101. 3- GENERAL ALERTS:
  102.  The number consists of 4 parts (see diagram below) which together form
  103.  a longword. (32 bits)
  104.  
  105.         +-+-------+--------+-----------------+
  106.         |x|xxxxxxx|xxxxxxxx|xxxxxxxx xxxxxxxx|
  107.         +-+-------+--------+-----------------+
  108.          | |     | |      | |               |
  109. Bit(s): 31 30   24 23    16 15              0
  110.  
  111.  The meaning of this number is as follows:
  112.  
  113.  Bit     31: This decides whether a number is a DEADEND or a RECOVERY
  114.              alert. If bit 31 is not set, it's a RECOVERY alert, which
  115.              means that you should be able to resume work after clicking
  116.              the left mousebutton. This kind of alerts usually appears
  117.              in an orange flashing box. If bit 31 is set, you have a
  118.              DEADEND alert, which means that your computer will reboot
  119.              and you lose all your unsaved work. This type of alerts
  120.              usually shows up in a flashing red box.
  121.              (Note: On kick 1.2/1.3 ALL alerts show up in a red box,
  122.               and a recovery alert usually reboots your computer.) 
  123.  
  124.  
  125.  Bits 24-30: The amiga operating system is divided in diferrent subsystems
  126.              like dos, intuition, graphics, etc.. Every subsystem has
  127.              its own code. The number here tells you which part of the
  128.              operating system caused the crash.
  129.  
  130.  Bits 16-23: This number indicates what the operating system couldn't do,
  131.              causing it to crash. This usually indicates things like
  132.              OpenLibrary, CreateLib etc... 
  133.  
  134.  Bits 0-15 : This part tells you what couldn't be opened, loaded, checked
  135.              etc... This indicates another subsystem.
  136.  
  137.  
  138. An example: dos.library couldn't open timer.device.
  139.  
  140.  The subsystem code for dos.library is $07000000, the errorcode for 
  141.  OpenDevice is $00040000, and the code for timer.device is $00008015.
  142.  This is a rather serious error, so it'll probably a deadend alert, which
  143.  means bit 31 will be set ($80000000). The final alert number will be:
  144.  
  145.  $80000000 ! $07000000 ! $00040000 ! $00008015 = $87048015.
  146.  
  147.  (ps: try TheGuru on this number, it really works !!) 
  148.  
  149.  
  150. WHAT IS 'THE GURU':
  151.  
  152.  'The Guru' is a simple database for guru numbers, and dos error numbers.
  153.  It's mainly intended as a tool for (system friendly) programmers.
  154.  
  155.  
  156. WHY USE IT ?:
  157.  
  158.  Because it makes debugging your programs quite a lot easier, since after
  159.  every crash the OS finds out what went wrong, and tries to tell you using
  160.  a guru or software alert; just write down the number and enter it in 'The
  161.  Guru' for a description of what went wrong. No more tedious searching
  162.  in books or inconcise descriptions, 'The Guru' solves it all !!
  163.  
  164.  Beside that (and this is useful for EVERY amiga owner) 'The Guru' also 
  165.  offers help on dos error numbers. You'll probably have seen something like
  166.  'Couldn't load xxx, error 205'. Just enter this number in 'The Guru' and
  167.  instantaneously you know that '205' means 'Object not found'.
  168.  
  169.  Happy bughunting!!
  170.  
  171.  
  172. BIG DUMMIES GUIDE:
  173.  
  174. BUTTONS:
  175.  
  176.  Here's a quick description of the various buttons and slider in the 'The
  177.  Guru' window:
  178.  
  179.  LEFT 'SET'  : Activate the guru display. You can now change it's contents.
  180.  RIGHT 'SET' : Activate the dos display. You can now change it's contents
  181.  
  182.  LEFT/RIGHT '<' and '>' : Change the cursor position in the active display.
  183.                           (The cursor is the brightest digit.)
  184.  
  185.  'GURU'      : Find the description of the current guru number.
  186.  'LAST'      : Fetches the last guru number from the system.
  187.  
  188.  'DOS '      : Find the description of the current dos error number.
  189.  'DEFAULT'   : Sets everything to zero and shows the logo.
  190.  
  191.  'ABOUT'     : Shows very important information about the program.
  192.  'QUIT'      : Guess...
  193.  
  194. KEYS:
  195.  
  196.  'G'         : Pressing the 'g' key is equivalent to clicking the 'GURU'
  197.                button.
  198.  'O'         : Equivalent to the 'DOS' button.
  199.  '<' and ',' 
  200.  and '<-'    : Equivalent to '<' for the active display.
  201.  '>' and '.'
  202.  and '->'    : Equivalent to '>' for the active display.
  203.  
  204.  'L'         : Equivalent to the 'LAST' button.
  205.  'R'         : Equivalent to the 'DEFAULT' button.
  206.  'U'         : Equivalent to the 'ABOUT' button.
  207.  'Q'         : Equivalent to the Quit button.
  208.  
  209.  '[TAB]'     : Switches active displays
  210.  '[1] to [9] and [A] to [F] : Same as the numeric buttons.
  211.  
  212.  '[RETURN]'   : Gets the description for the active display.
  213.  
  214. Just for an example try typing this string in 'The Guru' : 'r80000005'[ENTER]
  215.  
  216.  
  217. CUSTOMISING:
  218.  
  219.  'The Guru' can be customized using tooltypes:
  220.  
  221.   AUTOFRONT :
  222.   The window pops to front as soon as it's activated.
  223.   (can be useful if the window is obscured by some other windows)
  224.  
  225.   TOPAZ :
  226.   The Guru is fully font sensitive, and uses the default screen font for
  227.   text and buttons. If you don't like this you can specify this tooltype
  228.   to force The Guru into using Topaz 8.
  229.  
  230.   PUBSCREEN=Screenname : 
  231.   The Guru can open it's window on any public screen 
  232.  
  233.   LANGUAGE=Filename :
  234.   Different languages are supported through language files. The exact
  235.   format of a language file is specified in the language section. 
  236.   If this tooltype is not specified, the default language (english)
  237.   will be used.
  238.  
  239.   DATAFILE=Filename :
  240.   Specifies the exact filename and optional path of the data file.
  241.   If this tooltype is not specified, the default will be used, namely
  242.   the file Error.data in the same directory as the The Guru program.
  243.  
  244.  
  245. LANGUAGES:
  246.  
  247.  The Guru uses language files for languages other than english.
  248.  If you want to make your own language file, here's how:
  249.  
  250.  A language file is just a simple ascii file in the following format:
  251.  (line numbers are for clarity, NOT for inclusion in a language file)
  252.  
  253. 1 : Short description of the file
  254. 2 : Who did it
  255. 3 : (not used)
  256. 4 : Text for 'SET' button
  257. 5 : Text for 'GURU' button
  258. 6 : Text for 'LAST' button
  259. 7 : Text for 'DEFAULT' button
  260. 8 : Text for 'DOS' button
  261. 9 : Text for 'ABOUT' button
  262. 10: Text for 'QUIT' button
  263. 11: (not used)
  264. 12: Text shown if data-file not found (1 line!)
  265. 13: Response text to 12
  266. 14: Text shown if data-file corrupt (1 line!)
  267. 15: Response text to 14
  268. 16: Key shortcut for 'GURU' button (1 character, no Amiga-X or so)
  269. 17: Key shortcut for 'LAST' button
  270. 18: Key shortcut for 'DEFAULT' button
  271. 19: Key shortcut for 'DOS' button
  272. 20: Key shortcut for 'ABOUT' button
  273. 21: Key shortcut for 'PRINT' button 
  274.  
  275.  NOTES: Keep the text for buttons SHORT.
  276.  
  277.  WARNING: Do not make a language file any longer or shorter than the specs
  278.  above; it may lead to corrupt text output!
  279.  
  280.  
  281. SYSTEM REQUIREMENTS:
  282.  'The Guru' should run on any amiga with at least kickstart 1.2 .
  283.  It has been successfully tested on the following configurations:
  284.  
  285.  A3000 : 2 Mb CHIP, 4 Mb FAST, Kickstart 2.04
  286.  A3000 : 2 Mb CHIP, - Mb FAST, Kickstart 1.3
  287.  A3000 : 2 Mb CHIP,14 Mb FAST, Kickstart 3.1
  288.  A500+ : 2 Mb CHIP, - Mb FAST, Kickstart 2.04
  289.  A500+ : 2 Mb CHIP, - Mb FAST, Kickstart 1.3
  290.  A500  :0.5Mb CHIP,0.5Mb FAST, Kickstart 1.2
  291.  A1200 : 2 Mb CHIP, - Mb FAST, Kickstart 3.0 
  292.  
  293.  The program has also proven to be 100% enforcer and mungwall proof.
  294.  (Note: 'The Guru' produces one enforcer hit when clicking the 'LAST'
  295.   button. I don't know if there's a non system-private field to read
  296.   for the last guru number; currently I just read a long from $100...)
  297.  
  298.  
  299. GURU HISTORY:
  300.  
  301. version 1.0  (July 28,1993) : - Real crap version with bugs...
  302.                               - Released at SHN
  303.  
  304. version 1.1  (Aug.  1,1993) : - Fixed all bugs (I guess)
  305.                               - Never really released
  306.  
  307. version 2.0  (Oct. 31,1993) : This is a complete recode...
  308.                               - Better user interface
  309.                               - Better descriptions
  310.  
  311. version 2.1  (Dec. 25,1993) : - Added customization by tooltypes in icon
  312.  
  313. version 2.2  (Jan.  ?,1994) : Fixed a bug - opened a font but didn't free it
  314.                               - Added zoom gadget in window
  315.  
  316. version 2.21 (Jan.  6,1994) : - Window is now NOCAREREFRESH (=300% faster)
  317.                               - Added RMBTRAP, just looks nicer
  318.  
  319. version 2.3  (Feb.  3,1994) : A lot of changes on this one...
  320.                               - Looks at screen palette for correct 3d
  321.                                 buttons. (The buttons looked inversed on 
  322.                                 a kick 1.3 machine with 2.0 color palette)
  323.                               - Changed the logo, looks nicer
  324.                               - Looks good on a 2-color workbench too !
  325.                                 (now all text is readable...)
  326.  
  327. version 2.4 to 2.6          : - Miscellaneous fixes and changes
  328.  
  329. version 2.7  (Apr.  ?,1994) : - Added PUBSCREEN tooltype
  330.                               - Fixed a bug in window centering
  331.  
  332. version 2.8  (Jul. 12,1994) : - Changed format of data files slightly
  333.                               - Improved searching routines somewhat
  334.  
  335. version 2.9  (Sep. 22,1994) : - Changed gadget rendering (8 color Wb)
  336.                               - Fixed a bug in the data files
  337.                               - Second public release !!
  338.  
  339. version 3.00 (Nov.  8,1994) : - Redesigned GUI
  340.                               - Fully font sensitive (even on 1.3)
  341.                               - Added a lot of new guru and dos errors
  342.                                 and descriptions.
  343.                               - Localizable (?) (even on 1.3)
  344.                               - Loads of other little things
  345.  
  346.  
  347. BUG REPORTS:
  348.  
  349.  If you find a bug in The Guru please let me know.
  350.  Write down EXACTLY what you were doing at the time the bug showed up,
  351.  your configuration, and anything else that might be relevant.
  352.  Also I'd like to know if you know about any guru-numbers not yet included
  353.  in The Guru.
  354.  
  355.  My address is:
  356.  Emiel Lensink
  357.  Notengaarde 33
  358.  3992 JR Houten
  359.  Holland
  360.  
  361.  I will not reply to any mail unless you include a self-addressed envelope
  362.  and (if you don't live in Holland) an 'international reply coupon'. These
  363.  can be optained at your local post office.
  364.  
  365.  
  366. THE FUTURE:
  367.  
  368.  In my opinion 'The Guru' is completely finished, and no further updates
  369.  are planned. (except for some translated versions)
  370.  If you have any suggestions however, I'll be glad to hear about them,
  371.  and maybe they will eventually be implemented. (with your name in the docs,
  372.  Oooooh)
  373.  
  374.  My address is in the 'bugs' section.
  375.  
  376.  
  377. THE SOURCE:
  378.  
  379.  Yes, it's included. It's included for instructional purposes only, the
  380.  only person allowed to release updates or new versions of 'The Guru' is
  381.  me. It probably won't even assemble, because I make extensive use of macro's 
  382.  and custom includes.
  383.  
  384.  
  385. TECHNICAL SPECIFICATIONS:
  386.  
  387.  Program name    : The Guru 3.00
  388.  Author          : Emiel Lensink
  389.  Language        : 100% highspeed assembly
  390.  
  391.  Features        : - 101% operating system friendly
  392.                    - runs on all amiga's
  393.                    - looks pretty nice
  394.                    - written by me
  395.                    - can be configured
  396.                    - fully font sensitive
  397.                    - localizable
  398.                    - smooth scrolling text window
  399.                    - fast
  400.                    - can open on any public screen
  401.                    - written for only the Amiga
  402.                    - only 17204 bytes big
  403.  
  404.  Add-ons         : - multiple language files (to be released)
  405.  
  406.  'The Guru' was developed using the following equipment & software:
  407.  - A3000 , 2Mb CHIP, 14 Mb FAST, running kickstart 3.1
  408.  - Piccolo graphics board (better than AGA)
  409.  - Personal Paint
  410.  - Hisoft Devpac 3.04
  411.  - The Ultimate Graphics convertor (my own product, never finished)
  412.  - Enforcer & mungwall
  413.  - 3M & TDK floppy disks
  414.  
  415.  
  416. NOTE TO KICKSTART 1.3 USERS:
  417.  
  418.  'The Guru' 3.00 is still 1.3 compatible, but this is merely a patch of
  419.  some routines. Some features simply don't work, and I'm not going to
  420.  fix it; you fix it: UPGRADE !!
  421.  
  422.  The features not available are:
  423.  - Can't open on public screens (you don't even have them...)
  424.  - No zoom button
  425.  - Amigaguide docs may or may not work
  426.  - No error requesters (you don't have EasyReqArgs...)
  427.  - All tooltypes must end with '=' so 'AUTOFRONT' must be 'AUTOFRONT='
  428.  - Not very thoroughly tested
  429.  
  430.  Now don't write any complaining letters or so because I definitely
  431.  have stopped coding for 1.3 machines! Why don't you realise that you are
  432.  holding back AMIGA development; 1.3 compatible programs look crippled
  433.  when compared to their 2.0 only counterparts! Don't say '... but 1.3 does
  434.  everything I want it to do...'. Yeah, right... Be nice to your Amiga,
  435.  UPGRADE. 2.0 roms are available for next to nothing nowadays. UPGRADE.
  436.  
  437.  
  438. CRASHZERO:
  439.  
  440.  This is a very small program which causes your computer to crash with a
  441.  'Division by zero' alert. It was used during the development of 'The Guru'
  442.  for test purposes. Now that 'The Guru' is finished, this program is 
  443.  completely useless.
  444.  
  445.  
  446. SIMERR:
  447.  
  448.  This program generates a recovery alert. After this program has run, you
  449.  can click the 'LAST' button in 'The Guru' to retrieve the number shown in
  450.  the recovery alert. This program was made for test purposes only.
  451.  
  452.  
  453. FAULTS:
  454.  
  455.  This is a small cli-only program. It lists all the dos error codes in
  456.  your rom. It was made to find any undocumented dos error numbers.
  457.